UNIT NAME:  OVERLAY

  DECLARATION:  USES Overlay;

      REMARKS:  Turbo Pascal's overlay manager is implemented by the Overlay
                Unit.  The buffer management used by the unit keeps as many
                overlays in as possible in the overlay buffer to reduce disk
                reads for reloading overlays from disk.  There are two rules
                which must be observed when writing overlaid programs.

                  1)  All overlaid units must be compiled with the {$O+}
                      directive to ensure code generated can be overlaid

                  2)  At any call to an overlaid procedure or function, you
                      must ensure that all currently active procedures and
                      functions use the FAR call model (the {$F+} directive)

                NOTES:  The compiler will report an error if you attempt to
                        overlay a unit that was not compiled with the {$O+}
                        directive.

                        The only Turbo Pascal Standard Unit that can be
                        overlaid is the DOS Unit.

                        When using the IDE, programs containing overlays
                        must be compiled to disk

      EXAMPLE: 

                PROGRAM YourProg;

                   {$F+}         (* Force FAR call model *)

                USES

                   Overlay, DOS, CRT, YourMain, YourPrnt, YourEdit;

                   {$O YourMain}
                   {$O YourPrnt}
                   {$O YourEdit}

                BEGIN
                    .
                    .
                    .
                END.


                            CONSTANTS and VARIABLES 
 ----------------------------------------------------------------------------

      Const
          ovrOK          =  0;     (* Successful operation                 *)
          ovrError       = -1;     (* Overlay manager error                *)
          ovrNotFound    = -2;     (* Overlay file not found               *)
          ovrNoMemory    = -3;     (* Not enough memory for overlay buffer *)
          ovrNIOError    = -4;     (* Overlay file I/O error               *)
          ovrNoEMSDriver = -5;     (* EMS Driver not installed             *)
          ovrNoEMSMemory = -6;     (* Not enough EMS memory                *)

      Type
          OvrReadFunc = Function(OvrSeg : Word) : Integer;

      Var
          OvrResult    : Integer;     (* Overlay procedure/function result *)
          OvrTrapCount : Word;        (* Overlay manager intercept count   *)
          OvrLoadCount : Word;        (* Overlay manager load count        *)
          OvrFileMode  : Byte;        (* Access mode to pass to DOS        *)
          OvrReadBuf   : OvrReadFunc; (* Intercept overlay load operations *)

 ----------------------------------------------------------------------------

     OvrResult

     The OvrResult variable is used to store the result of procedures of
     procedures in the overlay unit as they are called.  The possible return
     codes are defined in the constants section of the Overlay Unit.


     OvrTrapCount

     Each time the Overlay Manager intercepts a call to an overlaid routine,
     either because the overlay is on probation or is not in memory, the
     OvrTrapCount variable is incremented.  The initial value is 0.


     OvrLoadCount

     The OvrLoadCount variable is incremented each time an overlay is loaded.

     You can determine the optimal size for you application by examining the
     OvrTrapCount and OvrLoadCount (in the debugger's Watch Window) during
     identicle runs and monitoring the effect of different probation area
     sizes (set with OvrSetRetry).


     OvrFileMode

     This value in OvrFileMode determines the access code to pass to DOS when
     the overlay file is opened.  The default value is 0 (Read-Only), but you
     may change the value to allow for shared file access on a network.


     OvrReadBuf

     This is a procedure type variable which allows you to intercept overlay
     load operations.  You can use this ability to implement your own error
     handline routines, or to test whether a removable disk is present.


                           PROCEDURES and FUNCTIONS 
 ----------------------------------------------------------------------------

  OvrClearBuf       Clears the overlay buffer
  OvrGetBuf         Gets the current size of the overlay buffer
  OvrGetRetry       Gets the size of the probation area
  OvrInit           Initializes the overlay manager; opens the overlay file
  OvrInitEMS        Loads the overlay file into EMS memory, if possible
  OvrSetBuf         Sets the size of the overlay buffer
  OvrSetRetry       Sets the size of the probation area